.Dd September 20, 2025
.Dt R_CORE 3
.Os
.Sh NAME
.Nm r_core
.Nd Radare2 Core Library API
.Sh SYNOPSIS
.In r_core.h
.Pp
.Sh DESCRIPTION
The
.Nm r_core
library provides the central functionality of radare2 and exposes it to programs and bindings. It integrates subsystems such as binary parsing, disassembly, analysis, emulation (ESIL), debugging, and interactive UI control. Callers use `RCore` to drive radare2 workflows: open a binary, run analyses, query information, and programmatically manipulate the project state.
.Pp
Important points for embedding and scripting:
.Bl -bullet
.It
.Nm RCore
is the single structure containing the state (io, bin, anal, debug, flags, etc.). Treat it as the main entrypoint for the API.
.It
Commands are the primary high-level control mechanism; use `r_core_cmd`/`r_core_cmd_str` to invoke existing r2 semantics from code.
.It
Many APIs return heap-allocated strings (for example `r_core_cmd_str`); the caller is responsible for freeing them.
.It
Analysis functions (`r_core_anal_fcn`, `r_core_anal_op`) populate internal structures that power higher-level operations (`pdf`, `af`, crossrefs). Run analysis before relying on function graphs.
.It
Seeking (`r_core_seek`) changes the current offset for subsequent commands; prefer absolute seeks for deterministic behavior in scripts.
.El
.Sh INITIALIZATION
.Ft RCore *
.Fn r_core_new "void"
.Pp
Allocate and initialize a fresh `RCore` instance with its subsystems (io, bin, anal, dbg, flags, etc.). The returned pointer is owned by the caller and must be freed with `r_core_free`.
.Ft void
.Fn r_core_free "RCore *core"
.Pp
Free an `RCore` instance and all associated resources. After calling this, the core pointer must not be used.
.Ft bool
.Fn r_core_init "RCore *core"
.Pp
Perform additional initialization on an existing `RCore` object. Most users call `r_core_new ()` which performs internal initialization already, but this is useful when embedding or recreating a core structure.
.Sh COMMAND EXECUTION
.Ft int
.Fn r_core_cmd "RCore *core" "const char *cmd" "bool log"
.Pp
Execute a textual radare2 command. This is the primary way to drive functionality from host programs: opening files (`o`), running analysis (`aaa`), printing (`pd`, `px`), and manipulating flags. `log` controls whether the executed command is recorded in the core's history/log.
.Ft char *
.Fn r_core_cmd_str "RCore *core" "const char *cmd"
.Pp
Execute a command and return its output as a newly allocated string. The caller is responsible for freeing the returned pointer (e.g., with `free ()`). This function is heavily used by language bindings and scripts that need to capture command output.
.Ft int
.Fn r_core_cmdf "RCore *core" "const char *fmt" "..."
.Pp
Format and execute a command (convenience wrapper). Useful to build commands with addresses or sizes without manual string handling.
.Ft int
.Fn r_core_cmd0 "RCore *core" "const char *cmd"
.Pp
Execute a command without recording it in the log or history. Use for internal operations or when performance matters.
.Sh SEEKING
.Ft bool
.Fn r_core_seek "RCore *core" "ut64 addr" "bool rb"
.Pp
Set the core's current offset to `addr`. Seeking affects subsequent commands that use the current address (for example `pd` or `px`). `rb` indicates whether the core should attempt to read bytes at the destination to validate the seek.
.Ft bool
.Fn r_core_seek_delta "RCore *core" "st64 addr"
.Pp
Move the current offset by a signed delta relative to the current position. Useful for short relative moves in scripts.
.Ft void
.Fn r_core_seek_previous "RCore *core" "const char *type"
.Pp
Seek to the previous item of a given `type` (for example a previous function or basic block). Useful to implement backwards navigation in tools that iterate over analysis results.
.Sh ANALYSIS
.Ft RAnalOp *
.Fn r_core_anal_op "RCore *core" "ut64 addr" "int mask"
.Pp
Analyze a single instruction at `addr` and return an `RAnalOp *` describing it. The returned `RAnalOp *` is owned by the caller and must be freed with `r_anal_op_free ()`. This API is ideal when you need structured, per-instruction information without running whole-function analysis.
.Ft bool
.Fn r_core_anal_fcn "RCore *core" "ut64 at" "ut64 from" "int reftype" "int depth"
.Pp
Perform function-level analysis starting at address `at`. This populates internal function graphs, basic blocks and cross-references and is typically followed by printing functions (`pdf`) or running decompiler stages.
.Ft void
.Fn r_core_anal_esil "RCore *core" "const char *str" "const char *addr"
.Pp
Evaluate an ESIL expression or code snippet. ESIL is radare2's emulation language; this function helps run small fragments or boot the ESIL VM for scripted emulation.
.Ft int
.Fn r_core_esil_step "RCore *core" "ut64 until_addr" "const char *until_expr" "ut64 *prev_addr" "bool stepOver"
.Pp
Step the ESIL VM until an address or condition is met. Useful to implement single-stepping or conditional traces programmatically.
.Sh DISASSEMBLY
.Ft int
.Fn r_core_print_disasm "RCore *core" "ut64 addr" "ut8 *buf" "int len" "int count" "enum r_pdu_condition_t pdu_condition_type" "const void *pdu_condition" "bool count_bytes" "bool json" "PJ *pj" "RAnalFunction *pdf"
.Pp
Format and print disassembly for a buffer or address range. High-level commands (`pd`, `pdf`) are implemented using this API; call it when you need controlled, fast formatting and optionally JSON output via `PJ`.
.Ft char *
.Fn r_core_disassemble_instr "RCore *core" "ut64 addr" "int l"
.Pp
Return a heap-allocated string containing the disassembly of a single instruction at `addr`. Caller must free it.
.Ft char *
.Fn r_core_disassemble_bytes "RCore *core" "ut64 addr" "int b"
.Pp
Disassemble `b` bytes starting at `addr` and return the output as a newly allocated string.
.Sh BINARY OPERATIONS
.Ft bool
.Fn r_core_bin_load "RCore *core" "const char *file" "ut64 baseaddr"
.Pp
Load a binary into the core for analysis. `file` accepts normal file paths and special providers used in tests (for example `malloc://SIZE` to create an in-memory file). After loading, analysis and printing commands operate on the loaded binary.
.Ft bool
.Fn r_core_bin_info "RCore *core" "int action" "PJ *pj" "int mode" "int va" "RCoreBinFilter *filter" "const char *chksum"
.Pp
Retrieve structured information about the currently loaded binary (sections, symbols, checksums). Use the `PJ` parameter for JSON formatted output.
.Ft bool
.Fn r_core_bin_set_cur "RCore *core" "RBinFile *binfile"
.Pp
Set the `RBinFile` used as current. Useful when the caller manages multiple binaries or wants to switch the active `RBinFile` without reloading from disk.
.Sh VISUAL MODE
.Ft void
.Fn r_core_visual "RCore *core" "const char *input"
.Pp
Enter the interactive visual mode driven by `RCore`. Frontends can call this to open the TUI and optionally feed initial key events or commands via `input`.
.Ft int
.Fn r_core_visual_refs "RCore *core" "bool xref" "bool fcnInsteadOfAddr"
.Pp
Show cross-references inside the visual UI. Parameters control whether to show XREFs and whether to present functions instead of raw addresses.
.Ft bool
.Fn r_core_visual_hud "RCore *core"
.Pp
Display or toggle the heads-up display (HUD) that shows contextual information in visual mode.
.Sh PROJECT MANAGEMENT
.Ft bool
.Fn r_core_project_open "RCore *core" "const char *file"
.Pp
Open and restore a previously saved `.r2` project. Projects replay seeks, flags and other persistent state so you can continue work without re-running expensive analyses.
.Ft bool
.Fn r_core_project_save "RCore *core" "const char *file"
.Pp
Save the current session to `file`. After a successful save you can restore it later with `r_core_project_open`.
.Ft int
.Fn r_core_project_list "RCore *core" "int mode"
.Pp
List available projects. This is handy for UIs exposing multiple saved sessions.
.Sh UNDO SYSTEM
.Ft void
.Fn r_core_undo_push "RCore *core" "RCoreUndo *cu"
.Pp
Push an undo record representing a reversible change. Frontends and scripts can use this to implement undo/redo flows for user actions.
.Ft void
.Fn r_core_undo_pop "RCore *core"
.Pp
Revert the last undo entry recorded in the core. Restores previous state (flags, bytes, metadata) as captured in the undo record.
.Ft void
.Fn r_core_undo_print "RCore *core" "int mode" "RCoreUndoCondition *cond"
.Pp
Print or query the undo history for display or automated rollback.
.Sh SEARCH
.Ft int
.Fn r_core_search_cb "RCore *core" "ut64 from" "ut64 to" "RCoreSearchCallback cb"
.Pp
Run a custom search between `from` and `to`, invoking the callback for each hit. This low-level API gives full control over match handling and early termination.
.Ft int
.Fn r_core_search_preludes "RCore *core" "bool log"
.Pp
Scan for common function preludes and heuristics to bootstrap function discovery in stripped binaries. Often used before calling `r_core_anal_fcn` or printing results.
.Sh EXAMPLES
.Pp
The examples below illustrate common real-world patterns found in the tree: capturing command output, using in-memory files in tests/fuzzers and combining seeking with single-instruction analysis.
.Bd -literal
/* Example 1: open, analyze and capture disassembly */
RCore *core = r_core_new();
r_core_cmd(core, "o /bin/ls", false);  /* open file */
r_core_cmd(core, "aaa", false);        /* run full analysis */
char *out = r_core_cmd_str(core, "pd 10"); /* capture output */
printf("%s\n", out);
free(out);                                /* must free returned string */
r_core_free(core);

/* Example 2: in-memory file used by fuzz tests (test/fuzz/fuzz_ia.c) */
RCore *r = r_core_new();
/* create an anonymous in-memory file of Size bytes */
r_core_cmdf (r, "o malloc://%zu", (size_t)4096);
/* write data into r->io using r_io_write_at (test code) */
r_core_cmd0 (r, "oba 0");  /* avoid history */
r_core_cmd0 (r, "ia");     /* run instruction analysis */
r_core_free (r);

/* Example 3: seek + single-instruction analysis */
RCore *c2 = r_core_new();
/* load binary first via r_core_cmd or r_core_bin_load */
r_core_seek(c2, 0x1000, true);
RAnalOp *op = r_core_anal_op(c2, 0x1000, R_ANAL_OP_MASK_BASIC);
if (op) {
    printf("Mnemonic: %s\n", op->mnemonic);
    r_anal_op_free(op);
}
r_core_free(c2);
.Ed
.Sh SEE ALSO
.Xr r_anal 3 ,
.Xr r_bin 3 ,
.Xr r_cons 3 ,
.Xr r_flag 3 ,
.Xr r_io 3
.Sh AUTHORS
The radare2 project team.
